feat(layer-4): SDK additive — live_fallback_mode + parent_agent_id kwargs (cueapi #823 + #824 parity)#44
Merged
mikemolinet merged 1 commit intoMay 13, 2026
Conversation
…args (cueapi #823 + #824 parity) Agent-id-split refactor Layer 4 OSS-SDK additives. Hosted cueapi shipped the substrate today (PR-A #823 schema + PR-B #824 router + PR-C #825 migration + #828 hotfix + PR-D #830 orphan-binding). cueapi-core OSS substrate port is DEFERRED to a future sprint (Backlog row cmp2zi9tl001w04jxcxw3ank1 — 4-layer dependency stack: agent_live_sessions convergence → Surface 6 OSS → Lane 1 OSS → Layer 4 OSS); this PR ships the additive SDK surface in parallel so hosted-cueapi users get the new kwargs immediately. Graceful degradation: hosted accepts; cueapi-core will 422 until precursors land. ## What ships - **`MessagesResource.send(live_fallback_mode=None)`** — per-message override for substrate's Live-fallback semantic. `"live_only"` queues until target Live agent's session is heartbeating; `"fallback_to_background"` falls through to Live-sibling's BG parent (via parent_agent_id) when Live is silent. Default `None` omits the field from the wire body — server applies its default (`"fallback_to_background"` per spec lock 22:11Z 2026-05-12). - **`AgentsResource.create(parent_agent_id=None)`** — caller-supplied `agt_<12alpha>` linking the new agent to a BG parent. `None` = BG agent (default — canonical entry point for a project). Substrate enforces same-tenant + 1-level hierarchy. When supplied without explicit slug, substrate auto-derives `<parent_slug>-live` (collision- suffix on per-user duplicates). Both kwargs are PURELY ADDITIVE — wire format identical to pre-Layer-4 callers when omitted. Docstrings cross-link the Backlog row + flag the hosted-vs-cueapi-core graceful-degradation contract explicitly so SDK users understand the OSS gap. ## Tests (8 new across 2 files) `tests/test_messages_resource.py::TestLiveFallbackMode` (3 tests): - live_fallback_mode omitted when None ⇒ field absent on wire - live_fallback_mode="live_only" passes through verbatim - live_fallback_mode="fallback_to_background" passes through verbatim `tests/test_agents_resource.py::TestCreate` (3 new in existing class): - parent_agent_id omitted when None ⇒ field absent on wire - parent_agent_id="agt_bg_parent" passes through verbatim - parent_agent_id combines cleanly with slug + webhook_url + display_name Full unit suite (161 tests): all pass. ## Companion artifacts - Backlog row cmp2zi9tl001w04jxcxw3ank1 updated 2026-05-13 ~00:32Z with explicit TRIGGER CONDITION (auto-pick-up when 3 OSS predecessors land) + LAST-VERIFIED EMPIRICAL STATE of cueapi-core (2 checks pinned for clean restart context). Future agent reading the row sees exactly what to verify before starting Layer 4 substrate port. ## cueapi-three-2 owns cli + mcp + action additives This PR is the cueapi-python additive only. Per PM CTO call msg_8e7b5f47, cli + mcp + action mirror additives are cueapi-three-2's lane. No overlap.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agent-id-split refactor Layer 4 OSS-SDK additives —
live_fallback_modekwarg onMessagesResource.send()+parent_agent_idkwarg onAgentsResource.create(). Both purely additive; wire format identical when omitted.Context
Hosted cueapi shipped the agent-id-split substrate refactor today: PR-A #823 schema + PR-B #824 router + PR-C #825 migration + #828 hotfix + PR-D #830 orphan-binding. Empirically proven on prod 2026-05-12 ~23:56Z (full bulletproof closed at msg_7ybpvzo9y2ve).
cueapi-core OSS substrate port is DEFERRED to a future sprint (Backlog row
cmp2zi9tl001w04jxcxw3ank1— 4-layer dependency stack: agent_live_sessions convergence → Surface 6 OSS → Lane 1 OSS → Layer 4 OSS). This PR ships the additive SDK surface in parallel so hosted-cueapi users get the new kwargs immediately.Graceful degradation contract: hosted-cueapi accepts both new fields; cueapi-core OSS will 422 until precursors land. Docstrings cross-link Backlog row + flag the contract explicitly.
Wire shape
live_fallback_modeNonefallback_to_background)live_fallback_mode: <value>in bodyparent_agent_idNoneparent_agent_id: <agt_xxx>in bodyTests (8 new across 2 files)
tests/test_messages_resource.py::TestLiveFallbackMode(3 tests):"live_only"passes through"fallback_to_background"passes throughtests/test_agents_resource.py::TestCreate(3 new in existing class):"agt_bg_parent"passes throughFull unit suite (161 tests): all pass.
Companion artifacts
cmp2zi9tl001w04jxcxw3ank1updated 2026-05-13 ~00:32Z with explicit TRIGGER CONDITION (auto-pick-up when 3 OSS predecessors land) + LAST-VERIFIED EMPIRICAL STATE of cueapi-core (2 checks pinned for clean restart context). Future agent reading the row sees exactly what to verify before starting Layer 4 substrate port.Out of scope
--live-fallback-modeflag +--parent-agent-idflag — cueapi-three-2's lanecueapi_send_message+cueapi_create_agentschema field additions — cueapi-three-2's lanelive-fallback-mode+parent-agent-idinputs — cueapi-three-2's lane🤖 Generated with Claude Code